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CHAPTER 1 


DB: THE ATARI DEBUGGER 


Db is a debugger for the Atari ST series. It is indended to replace sid as 
the assembly-level debugger of choice. It is not a source-level debugger, but 
it does handle both Alcyon C and Mark Williams C (new and old) symbol table 
formats. 

Db can use any of the ST f s character devices for its input and output, includ¬ 
ing the screen, the serial port, and the MIDI port. The I/O device is 
selected with a switch on the command line (or in the TTP window if started 
from the desktop). 

Db is capable of debugging programs running on one machine while the bulk of 
the debugger runs on another. This is called remote debugging , and permits 
debugging of operating systems while they boot, for example. This feature is 
described in the chapter REMOTE DEBUGGING. 


USAGE 

From a command shell, db can be started as follows: 

db [ options ] [ program [ args ... ] ] 

If started as a TTP program from the desktop, the arguments line looks the 
same without the word db at the beginning. 


OPTIONS 

Db can use any device for its input and output. This makes debugging 
graphics- and kefyboard-oriented programs easier. 

The options on the command line select the output device to use: 


S 


Use GEMDOS to access the ST screen and keyboard. This is the default 
case, but it does have limitations. See the section DB AND GEMDOS in 
the chapter OPERATING SYSTEM CONSIDERATIONS for more information. 


-b 


Use the BIOS to access the ST screen and keyboard. Sometimes this 
helps when debugging a program which itself does BIOS I/O, because 
using GEMDOS calls can mess up type-ahead and the like. 
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-s 

Use the serial (RS232) port. A terminal or an ST running a terminal 
program must be connected via a "null modem" cable, and its keyboard 
and screen are used for communicating with the debugger. (You can 
even use a modem connection to a terminal or computer, but this is 
extreme.) The baud rate, parity, etc. for the serial port must be set 
before starting the debugger in this mode. 


-m 


Use the MIDI port. An ST running a terminal program which uses the 
MIDI port must be connected with a double-MIDI cable (i.e. MIDI OUT -> 
MIDI IN and MIDI IN -> MIDI OUT) . One such program is midi term, 
included on the distribution disk with the debugger. It is a minimal 
terminal emulator program, but it gets the job done. 


In the last two modes, the debugger controls the serial or midi port 
hardware directly, without going through GEMDOS or the BIOS, so there are 
fewer limitations on debugging programs which use GEMDOS or the BIOS. 
However, the the limitations with respect to the operating system always 
apply, except when remote debugging. See the section DB AND GEMDOS in the 
chapter OPERATING SYSTEM CONSIDERATIONS for more information. 

In addition, the -f option can be used for debugging the debugger: the 
option -f N (where N is a decimal number greater than 128) causes db to use 
Xbios function code N rather than the default of 11. This is only useful 
because it lets you locally debug the head-side of a remote-debugger. 


Usage examples: 


db 

db -s myprog.prg -z 

start the debugger; use GEMDOS for I/O 
use the serial port for I/O; load 
myprog.prg for execution, with the 
command-line argument -z 


TERMS 

Several terms are used throughout this document which must be defined 
here. 

The client is the program you are debugging. 

The head is the part of the debugger which handles all the user input and 
output. The commands you type are translated by the head into commands 
for the stub . It is the stub which causes the client to run, processes 
breakpoints, and catches exceptions like bus error. The stub reports 
these events to the head, which reports them to you. 

When you are remote debugging , the head runs on the master machine, and 
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the stub and client run on the slave machine. The head gives commands to 
the stub and receives the stub’s responses through the communications 
layer, which actually talks over the MIDI cable. 

The term debugger is used to refer to the head, stub, and communications; 
in short, everything but the client (program) and the user (human). 

You cause the client to execute instructions with the g (go), t (trace), u 
(untrace), and v (verbose-trace) commands, collectively known as trace)go 
commands. A stop is anything which causes a trace/go to stop: a bus 
error, address error, or other processor exception , a breakpoint whose 
count has reached zero, and a memory checkpoint which becomes true. 
Memory checkpoints are evaluated at times called opportunities , which 
occur when processing exceptions (including the illegal-instruction excep¬ 
tion caused by breakpoints and the trace exception which happens between 
instructions of a trace). 

You can put a list of commands to be executed in a file, and cause those 
commands to be executed by the debugger using the load command. Such 
files are called scripts . 


USING THE DEBUGGER 

When the debugger is started, it processes its GEMDOS command line first. 
If there are any options (like -m or -s) they are checked and dealt with. 
Then, if there is a program argument, that program is loaded off disk and 
set up for executing. It becomes the client. 

Next, if there are any args they are placed in the client’s basepage, as 
GEMDOS command-line arguments to it. When the client is completely set up 
and ready to run, the debugger prints out its basepage information (text 
size, environment pointer, etc.). This client set-up amounts to the same 
thing as using the exec command. 

The debugger then looks for and loads your configuration file (that is, it 
executes the commands found there; such files are called scripts). The 
first place it looks is the current directory, for a file called db.rc. 
If that file doesn’t exist, it looks for the file named in the environment 
variable DBRC. If there is no such environment variable, it looks for the 
file db.rc in the root directory of the current device. If none of these 
files exists, the debugger simply continues with the start-up procedure. 

When remote debugging, the autoload procedure is the same, except that the 
debugger looks for rdb.rc, then the file named in the environment variable 
RDBRC. 

Whether or not there was a program argument to execute and/or a startup 
file, the debugger ultimately displays its prompt, a colon (”:”). Any 
time you see the colon prompt, the debugger is waiting for you to type a 
command line. Command lines consist of commands and their arguments. 
Multiple commands on one command line are separated by semicolons (";"). 
Multiple-letter commands must be separated from their arguments by a space 


@ 1988 Atari Corp. 


3 


DB 


ATARI DEBUGGER 


AUGUST, 1988 


(e.g. "where 12322"), while single-letter commands need no space (e.g. 
"di2322"). 

You can always use “S (control-S) to stop the debugger's output and "Q to 
start it again. You can usually use *C to abort a command, especially 
commands which generate long listings. 

When debugging programs compiled under Mark Williams C, you need to play a 
trick before you start the program. See the section DB AND HARK WILLIAMS C 
in the chapter OPERATING SYSTEM CONSIDERATIONS for more information. 

When remote debugging, the debugger will display its version number, then 
wait for the stub to respond before loading the configuration script. 
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CHAPTER 2 


EXPRESSIONS, RANGES, AND STRINGS 


This chapter describes how values are entered to the debugger, mostly as argu¬ 
ments to commands. An expression is something which boils down to a single 
numeric value. A range is something which boils down to a starting address 
and a length: count of bytes. A string is something which boils down to a 
series of bytes. A section on each follows. 


EXPRESSIONS 

An expression can be used any time a numeric value (like an address or 
count) is expected. All expressions evaluate to 32-bit integers. Overflow 
is checked for when reading a constant (so the hex constant SFFFFFFFFO 
would cause and error because it requires 36 bits). Overflow is not 
checked for in any other situation. There are two kinds of expressions: 
simple expressions and complex expressions. 


SIMPLE EXPRESSIONS 

Simple expressions contain no operators and are not enclosed in 
parentheses. There may not be any spaces in a simple expression. 
Simple expressions take one of the following forms: 


hex constant 
%hex constant 

A hex constant has the obvious value. The leading , $ t is 
optional: with no prefix, a number is assumed to be hexadecimal. 
Hex constants consist of an optional sign (+ or -) followed by one 
or more of the digits 0-9, A-F, and a-f. 

Examples: 0, 1, 3FA, 13aD4, ffffa4d0, -5b30 (same as ffffa4d0). 


@decimal constant 

A decimal constant begins with an at-sign ("§"), then an optional 
sign ( + or -), then one or more digits 0-9- It has the obvious 
value. 

Examples: @0, @99, @-32768 (same as ffff8000). 


~octal constant 

An octal constant begins with a circumflex (up-arrow, "~"), then 
an optional sign (+ or -), then one or more digits 0-7- It has 
the obvious value. 


AUGUST, 1988 


ATARI DEBUGGER 


DB 


DB 


ATARI DEBUGGER 


AUGUST, 1988 


Examples: *0, '77. *20000000000 (same as 80000000). 


%binary constant 

A binary constant begins with a percent-sign ("#"), then an 
optional sign (+ or -), then one or more digits 0-1. It has the 
obvious value. 

Examples: #0, #1010, #1000000000000000 (same as 00008000). 


.symbol 

A leading period (' .') indicates that what follows is a symbol 
specification. The value of the expression is the 32-bit value in 
the symbol's value field. A symbol specification can simply be 
the name of the symbol (e.g. ".start") or something more complex. 
See the chapter SYMBOLS AND DEBUGGER VARIABLES for more informa¬ 
tion. 

Examples: .main, .gemlib:xmain:_main:L3 


'variable 

A leading backquote (’’'') indicates that what follows is a 
debugger variable name. The value of this expression is the value 
in the corresponding debugger variable. See the chapter SYMBOLS 
AND DEBUGGER VARIABLES for more information. 

Examples: 'd0, 'clientbp, 'mtype 


&;variable 

A leading ampersand ('&') indicates that what follows is a 
debugger variable name, and the value of this expression is the 
address of the storage for indicated variable in the stub's 
memory. These variables should not be changed, since the 
debugger’s local copy of the variable might overwrite your change. 
However, these addresses can be used in memory checks to set 
checkpoints on the values in registers. 

See the section DEBUGGER VARIABLES in the chapter SYMBOLS AND 
DEBUGGER VARIABLES (especially the subsection Client Registers, 
and the section MEMORY CHECKPOINTS ON VALUES IN REGISTERS in the 
chapter THE CLIENT, BREAKPOINTS AND CHECKPOINTS: DETAIL for more 
inf ormation. 

Examples: &dl, &pc, &sr 


The dollar-sign alone is short for '$. This temporary variable is 
set to the result of the last math command (that is, just an 
expression on the command line). In addition, the f (find) 
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command sets $ to the address of the start of the first match. 
Example: $ 


COMPLEX EXPRESSIONS 

A complex expression is a LISP-like expression containing parentheses, 
operators and operands in prefix notation. Unlike simple expressions, 
there may be spaces in a complex expression. 

The first element within the parentheses of a complex expression must 
be an operator. The second and subsequent elements must be expres¬ 
sions (simple or complex) which are used as operands for that opera¬ 
tor. 

In the following table of operators, "exp ..." means "one or more 
expressions." For the logical operators (and the if command), zero is 
"false" and anything nonzero is "true." The logical operators them¬ 
selves all return the number 1 if the expression is TRUE. 


FORMAT COMMENTS 


(+ exp . . .) 

(- expl exp2) 

(* exp ...) 

(/ expl exp2) 
(% expl exp2) 
(& exp ...) 

(| exp ...) 

(* exp ...) 

(~ exp) 

(lpeek exp) 
(wpeek exp) 
(peek exp) 

(= expl exp2) 
(&& expl exp2) 
(|| expl exp2) 
(~~ expl exp2) 
(! exp) 

(> expl exp2) 
(< expl exp2) 
(s> expl exp2) 
(s< expl exp2) 


Add the expressions together 

Subtract exp2 from expl 

Multiply the expressions together 

Divide expl by exp2 

Return expl modulo exp2 

Bitwise AND the expressions together 

Bitwise OR the expressions together 

Bitwise EXCLUSIVE OR the expressions 

Bitwise NOT (invert) the expression 

Returns the longword at address exp 

Returns the word at address exp 

Returns the byte at address exp 

TRUE if the expressions are equal (also ==) 

Logical AND of the two expressions 

Logical OR of the two expressions 

Logical EXCLUSIVE OR of the two expressions 

Logical NOT of the expression 

TRUE if expl > exp2 (unsigned) 

TRUE if expl < exp2 (unsigned) 

TRUE if expl > exp2 (signed) 

TRUE if expl < exp2 (signed) 


Here are some examples of complex expressions and what they evaluate 
to: 
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EXPRESSION 

VALUE 

COMMENTS 

( + 

2 3 3) 

8 

simple addition 

(- 

7 5) 

2 

simple subtraction 

(* 

(+ 2 1) 3) 

9 

nested complex expressions 

( + 

'clientbp 100) 


gives the client 1 s text base 

( + 

4 'd0 *a0) 


gives the EA of 4(d0.1,a0) 

( + 

(+ 3 1) (/ (* 2 

8 

in algebraic notation: 

8 ) 

4)) 


(3 + 1) + ((2 X 8 ) / 4) 


RANGES 

A range is a way to specify a block of memory. A range consists of a 
start address and either an end address or a count. For most commands 
which take a range, the start and count values have defaults, so not all 
parts of the range need to be typed in. 

A fully-specified range can look like "start,end" or "s tart[count ]" (where 
start, end, and count are expressions, and the brackets and commas must be 
typed as shown). If the end address is present, it is the first address 
not included in the range: 100,200 specifies the range of addresses from 
100 to IFF. 

Various parts of the full specification can be omitted. A range which 
uses the default start address looks like " .end " (note the leading comma, 
showing that start was omitted) or "[count]" (the brackets set off count 
and show that start was omitted). If you want the default count the range 
just looks like "start" (which also looks like any other expression). 

Here are some examples and the ranges they specify, assuming a default 
start of 100 and a default count of 80 (all numbers are hex): 


RANGE 

START 

END 

COMMENTS 

200 [ 70 ] 

200 

26F 

no defaults; start[count] form 

200 

200 

27F 

default count 

[70] 

100 

16F 

default start; [count] form 

80,100 

80 

FF 

no defaults; start,end form 

,200 

100 

IFF 

default start; ,end form 


Sometimes the start and/or count fields have no defaults; in these cases, 
they must be specified. Also, the start[count ] form is not always 
allowed. This is the case for the g (go) command, where a count of bytes 
to execute does not make sense. 

The default start and count values are listed in the descriptions for all 
commands which take a range argument. 
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STRINGS 

Strings are used by the f (find) and s (set) commands, A string consists 
of characters surrounded by double-quotes (" string") or single-quotes 
('string'). The string acts like the sequence of bytes represented by the 
characters between the quotes, with the following escapes: 


ESCAPE 

MEANING 

\b 

backspace ($08) 

\e 

escape ($1B) 

\f 

formfeed ($0C) 

\n 

linefeed ($0A) 

\r 

carriage return ($0D) 

\t 

tab ($ 09 ) 

w 

the single character backslash ($5C) 

\? 

the special "wildcard" escape (see find) 

\xXX 

the byte $XX where XX is two hex digits 


Quotation marks are also used to set off parts of commands and keep semi¬ 
colons from splitting up a command. See the chapter IF, GOTO, DEFER, AND 
ALIAS for more information. 
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CHAPTER 3 


THE CLIENT, BREAKPOINTS, AND MEMORY CHECKPOINTS: AN OVERVIEW 


RUNNING THE CLIENT PROGRAM 

Once there is a client ready to run (loaded with the exec command or with 
a program argument on the debugger's command line), you can cause it to 
run with the g (go), t (trace), u (untrace) , and v (verbose-trace) com¬ 
mands. Collectively, these are called trace/go commands. What follows 
are cursory descriptions. See the chapter THE CLIENT, BREAKPOINTS AND 
CHECKPOINTS: DETAIL for more information. 

The g (go) command runs the client at full speed. It will only stop when 
something exceptional happens, like hitting a breakpoint or causing a bus 
error. You can also stop it by hitting the stop button, if you have one. 
See the section STOP BUTTONS in the chapter REMOTE DEBUGGING for more 
information. 

The t (trace) and u (untrace) commands cause the client to execute just a 
few instructions (sometimes just one) and then stop and display the regis¬ 
ters. The v (verbose trace) command causes the client to execute one 
instruction, display those registers which have changed, then execute the 
next instruction, and so on. You can "trace through" a subroutine this 
way, or even trace through entire programs. The advantage is that the 
client doesn't get out of your control: the stub gets an opportunity to 
check memory checkpoints between each instruction, and you can stop the 
client after executing a certain number of instructions, even if those 
instructions are part of (say) an infinite loop. Naturally, tracing is 
significantly slower than full speed, because of all the processing going 
on in the stub. For just one or a few instructions, however, the speed 
doesn't really matter much, anyway. 

Trace and untrace are almost identical. They differ in their treatment of 
the "trap" instruction. See the section TRACE AND UNTRACE in the chapter 
THE CLIENT, BREAKPOINTS AND CHECKPOINTS: DETAIL for more information. 


BREAKPOINTS 

Breakpoints allow you to stop the client program when it is about to exe¬ 
cute an instruction at a specific address. A counted breakpoint allows 
you to stop the client the n-th time the instruction is executed. 

You set breakpoints with the b command. When you set breakpoints and use 
the trace/go commands, the trace/go is stopped if the PC matches any 
breakpoint address and the count for that breakpoint (if any) has expired. 
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The section BREAKPOINTS IN DETAIL goes into breakpoints more completely. 
MEMORY CHECKPOINTS 

Memory checkpoints cause a stop based on the contents of memory, rather 
than before executing a particular instruction. You set checkpoints with 
the m command. When you set checkpoints and do a trace/go, the trace/go 
is stopped when any of the checkpoint expressions becomes TRUE. (Note the 
word "becomes" — memory checkpoints are "edge triggered" rather than 
static. See the chapter THE CLIENT, BREAKPOINTS AND CHECKPOINTS: DETAIL 
for more information. 

Checkpoints are of two types: region and comparison. Region checkpoints 
cause a stop when a change is detected in a region of memory (e.g. an 
array or the screen). Comparison checkpoints cause a stop when the com¬ 
parison evaluates to TRUE when previously it was FALSE. 

Unlike breakpoints, which cause an exception in the processor, memory 
checkpoints need to be evaluated by the stub. The times when the stub 
gets a chance to evaluate checkpoints are called opportunities. Briefly, 
opportunities occur between instructions of a trace (verbose or normal) or 
untrace, and during the processing of a breakpoint (even if that break¬ 
point, because of its count, doesn't cause a stop). 

Since memory checkpoints only get evaluated during an opportunity, they 
can only cause a stop at those times. Thus, all you know is that the 
expression became TRUE sometime between the previous opportunity and this 
one. In the case of trace and untrace, the opportunities come between 
every instruction. But in the case of a go command, you don't know just 
when the previous opportunity was. 

Breakpoints cause an opportunity even when their counts have not yet 
expired. You can provide an opportunity explicitly by placing a break¬ 
point with a count of "never" — for instance, at the beginning of a loop. 
Such breakpoints never cause a stop by themselves, but always cause an 
opportunity. 

See the chapter THE CLIENT, BREAKPOINTS AND CHECKPOINTS: DETAIL for more 
information. 
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CHAPTER 4 


COMMANDS 


The debugger prompts the user for a command with a colon ). Commands can 
also be read from text files (see the load command), aliases (see the alias 
command) and the client (see the indirect command). In each case, multiple 
commands can be specified on one line by separating them with semicolons 
(";"). If you really mean to use a semicolon (for example, in a comment or in 
an argument to the print or echo commands), the argument containing the semi¬ 
colon can be enclosed in quotation marks ( ff ) or apostrophes (also called 
"single quotes : M " ,,f ). See the chapter IF, ALIAS, AND DEFER for more informa¬ 
tion. 

The simplest kind of command is simply an expression. Typing an expression 
alone causes that expression to be evaluated, and the result to be printed in 
hex, decimal, octal, and binary. The result is also placed in the debugger 
variable '$ for future use. This kind of command (which usually just does 
some math) is called a math command. 

In the following list of debugger commands, these syntax rules are used: 

Brackets ("[ ]") surround optional items. Italics are used for the name of 
something you type (i.e. "d range" means the letter * d f followed by a range 
specification). Three dots ("...") means the previous item can be repeated 
one or more times. Several alternatives enclosed in braces and separated by a 
vertical bar ("{ a | b }") means either a or b, but not both. Several items 
surrounded by both brackets and braces means you can use one of the things 
inside the braces, or nothing at all: 

transcript [ { off | flush | printer | file [ a ] } ] 

means that the following forms are valid: 

transcript none of the alternatives 

transcript off the off alternative 

transcript flush the flush alternative 

transcript printer the printer alternative 

transcript myfile the file alternative without f a’ 

transcript myfile a the file alternative with r a' 

Note that sometimes the brackets and braces should really be typed: this is 
the case for the brackets in range specifications and the braces in an 
indirect operand to a memory checkpoint. The description of the command 
should make these exceptions clear. 

The commands are divided into these groups: 
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SECTION 

COMMANDS 


Breakpoints and checkpoints 

b, nb, m, nm 


Trace and go 

t, U, v, g 


Memory handling 

1 , d, s, f 


The Client and symbols 

exec, args, getsym, sym, ?, where 

, stack 

Registers and variables 

x, vars, stubstate 


Remote commands 

wait, check, terminate, continue 


Files and aliases 

dir, read, write, load, unload, 
goto, fgoto, alias, unalias, ! 

reload. 

Miscellaneous commands 

abort, #, transcript, exit, quit, 
echo, print, if, indirect 

help. 


BREAKPOINTS AND CHECKPOINTS 

Breakpoints and checkpoints are what cause a trace/go to stop. See the 
section CHECKPOINTS ON THE VALUES IN REGISTERS in the chapter THE CLIENT, 
BREAKPOINTS AND CHECKPOINTS: DETAIL for more information. 


b 

b [ tiindex ] [ address [ { count ' | never } ] ] 

The b command alone lists the active breakpoints. With an address, it 
sets a breakpoint (with a count of one) at that address, and removes 
all other breakpoints there. With a count, it sets a counted break¬ 
point at the address, and removes all other breakpoints there. With 
never, it sets a breakpoint which will never cause a stop. (This is 
useful because it creates an opportunity for memory checkpoints.) 

If the #index argument is present, the new breakpoint is placed in 
slot number index. If there was already breakpoint in that slot, the 
old one is removed first. This option is useful when using auto¬ 
execute aliases. See the section AUTO-EXECUTE ALIASES in the chapter 
IF, GOTO, DEFER, AND ALIAS for more information. 


Examples: 



b 

list all breakpoints in the table 


b .main 

set a breakpoint to stop at the label "main" 

b .main 1 

same as above 


b .loop 3 

set a breakpoint to stop the third time 
instruction at "loop" is executed 

the 

b #4 .loop 

set a breakpoint at .loop in slot #4, 

re- 


placing whatever breakpoint was in 

that 


slot, and replacing any other breakpoint 
that address. 

at 
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nb [ { address | ft index } ] 

The nb command alone removes all breakpoints. It asks for verifica¬ 
tion first: space, f y', and mean M go ahead." Any other key aborts. 
With ttindex , it removes breakpoint number index . With address , it 
removes all breakpoints at address . 

Note that you need to have a space between nb and its argument * becase 
nb is not a one-character command. 


Examples: 

clear all breakpoints (asks for verifica¬ 
tion) 

clear the breakpoint in slot number 1 
clear all breakpoints at the label "loop" 


nb 

nb #1 
nb .loop 


m 

m [ ttindex ] range 
m [ ttindex ] address .size 

m [ ttindex ] address [ .size ] op { value | {iaddr } | old } 

The m command alone lists all memory checkpoints. 

With a range , it sets a range-type checkpoint. The default count for 
range is 2 (a word); there is no default start. 

With an address and a size (but no op or value) it sets a range-type 
checkpoint starting at the given address with a length of 1, 2, or 4, 
depending on the size (b, w, or 1). Note that address may be a com¬ 
plex expression; see the examples. 

The last form sets a comparison checkpoint, as follows: 

The . size field is either .b, .w, or .1. The size field can be omit¬ 
ted, but if it is present, there must be no space between it an the 
address argument. That is, ".flag.b" is correct for a byte-size 
checkpoint address and size, while ".flag .b" is not. If . size is 
missing, the default is .w (two bytes). 

(Unfortunately, since the memory checkpoint command uses the trailing 
part of the address argument as a size indicator (.b, .w, and .1), you 
can't have a checkpoint on a compound symbol specifier whose last com¬ 
ponent is a two-character symbol starting with a period ( , . t ).) 

The op (operator) can be one of the following: 


© 1988 Atari Corp. 


15 



DB 


ATARI DEBUGGER 


AUGUST, 1988 


OPERATOR 

COMMENTS 

s> s<= s>= s< 

Signed comparison 

u> u<= u>= u< 

Unsigned comparison 

== ! = 

Equal, not equal 

vs VC 

Overflow set, overflow clear 

><=>=< 

Same as signed 

= 

Same as == 

cs cc 

Same as u< and u>= 


If the operand is enclosed in braces, it is indirect: iaddr is the 
address of the operand used for the comparison. When the checkpoint 
is evaluated, as many bytes are fetched from iaddr as are used at 
address -- that is, the size of the checkpoint controls them both. 

If the operand is the word old, it means to use the initial value at 
address for the subsequent comparisons. This lets you catch a byte, 
word, or long value when it changes, and is faster than the equivalent 
range-type checkpoint. The "old" value is reloaded internally at the 
start of each trace/go command. 

Otherwise, the operand is evaluated as an expression, and its value is 
used for the comparisons. 

Note that for the indirect comparison type, a pair of braces encloses 
the second operand ("{iaddr}" in the example). You really type the 
braces; they are not there to show syntax. 

If the if index argument is present, the new checkpoint is placed in 
slot number index . If there was already a checkpoint in that slot, 
the old one is removed first. This option is useful when using auto¬ 
execute aliases. See the section AUTO-EXECUTE ALIASES in the chapter 
IF, GOTO, DEFER, AND ALIAS for more information. 


Examples: 



m 


List memory checkpoints 


m 

.foo > 10 

Stop when foo.w (default size) > 10. 


m 

.foo > old 

Stop when foo.w exceeds its initial value. 


m 

.buf[10] 

Stop when anything in the 16 bytes starting at 
changes. 

buf 

m 

#3 .buf[10] 

Same as above, but place the checkpoint in slot 

#3. 

m 

438.1 

Same as "m 438[4]" 


m 

(+ 2 2).w 

Same as "m 4.w" and "m 4[2] n 


m 

438.1 < {43C} 

Stop when the (long) value at 438 is less than 
(long) value at 43C. 

the 

m 

12030 != old 

Stop when 12030.w changes value. 


m 

12030 [ 2 ] 

Stop when 12030.W changes value (see below). 


m 

12030 

Same as above (default count is 2). 



Notice the last three examples. They all seem to do the same thing: 
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stop when either of the two bytes starting at 12030 changes. The 
range type is less desirable, though, for checking small areas (one, 
two, or four bytes), because the range type computes the CRC (cyclic 
redundancy check) for the range, and compares it to what the CRC was 
when the trace/go started. This takes a long time, and, more impor¬ 
tantly, certain changes can actually be missed if both the original 
and new contents result in the same CRC value. 


nm [ { address | #index } ] 

The nm command alone, like the nb command, clears all the memory 
checkpoints. It asks for verification first: space, ? y f , and 1 Y 1 mean 
"go ahead," any other key aborts. With address , the command clears 
all checkpoints with that address. With if index, the command clears 
checkpoint number index . 


Examples: 
nm 

nm #3 
nm .flag 


Clear all checkpoints. Ask 
for verification first. 

Clear checkpoint number three. 
Clear all checkpoints with the 
value of "flag" as the ad¬ 
dress . 


TRACE AND GO 

The trace and go functions are the only ones which cause the client to 
execute instructions. 

t [ { count | x | w } ] 

The t (trace) command causes the client to execute in "trace mode." 
With no count, the client executes one instruction. With a count, the 
client executes that many instructions. With a count of , x ! , the 
client executes "forever" — until a breakpoint, memory checkpoint, or 
exception causes a stop. 

With a count of ’w’ , the t command executes one instruction at full 
speed. This is only meaningful if that is a "jsr" or "bsr" instruc¬ 
tion: in those case, the whole subroutine is executed all at once, and 
the trace stops at the instruction following the "jsr" or "bsr." 

See the section TRACE AND UNTRACE in the chapter THE CLIENT, BREAK¬ 
POINTS AND CHECKPOINTS: DETAIL for more information. 


u [ { count | x } ] 

The u (untrace) command is just like the t (trace) command, except 
that the client executes in "untrace mode." This means that trap-type 
instructions are not treated specially. Note that uw doesn’t make 
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sense and isn't allowed. 


v [ u ] [ count ] 
vw 

The v (verbose-trace) command begins another kind of trace: before 
each instruction is executed, it is disassembled and displayed on the 
screen. After it executes, the values of all registers which changed 
are displayed. Then the next instruction is disassembled, and so on. 
Use ~S to pause the trace, ~Q to continue it, and ~C to stop it. 

With no count , the v command will trace forever (until a stop or until 
~C is used). The verbose trace executes in "trace" mode, meaning that 
a trap handler is executed as though it were a single instruction. 
With a count , that many instructions are disassembled and executed. 

With 'u* , this command traces instructions in "untrace" mode. 

The command vw works like tw: one instruction is executed at full 
speed, the same as a "go" command with a temporary breakpoint set at 
the next instruction. The difference is that with vw, after the "go" 
stops, only the registers which changed are shown. Like tw, this is 
mostly used to go through subroutines at full speed: rather than v, 
use vw at the JSR or BSR instruction. 


Examples: 


t 

trace one instruction 

1 4 

trace four instructions 

tx 

trace forever (until a stop) 

tw 

execute through a subroutine at full speed 

u 

untrace one instruction 

u 4 

untrace four instructions 

ux 

untrace forever (until a stop) 

V 9 

verbose-trace 9 instructions 

V 

verbose-trace forever (until a stop) 


g [ range ] 

The g (go) command causes the client to execute at full speed. It 
turns control of the computer over to the client, after setting the 
breakpoints. The go will only stop when a breakpoint, exception, or 
the stop button causes a stop. 

The default start address for range is the current PC. The default 
count means "forever." In fact, you can't specify a count for this 
range; you can only use the "start" or "start,end" or ",end" forms of 
the range. If you specify an end, a temporary breakpoint is set at 
that address. This is sometimes called "go until," because you are 
saying, "Go until this spot, then stop." See the examples below for 
more. 
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Examples: 



S 

Go forever (until an exception or break¬ 
point) 

g .main 

Set PC to main, then go. 


g ,.subproc 

Set a temp, breakpoint at subproc. 

then go. 

g .main,.subproc 

Set PC to main, set a breakpoint 
proc, and go. 

at sub- 


Note that the "go until" forms actually go until the end address or 
some other exception. Note also that they clear the temporary break¬ 
point when the go stops, for whatever reason. Finally, note that 
there must be at least one breakpoint slot available for the "go 
until" to work. 


MEMORY 

The following commands display and set memory in various ways. 


1 [ range ] 

The 1 (list) command disassembles memory into 68000 mnemonics. The 
default start for range is the place where the last 1 command left 
off, but the exec command and all the trace/go commands set the 
default start to the new PC after the command is finished. The 
default count for range produces 12 lines of disassembly, not any par¬ 
ticular number of bytes. 

The list command takes the range as a guideline: the last instruction 
it disassembles is the one containing the last byte of the range, even 
if the instruction extends beyond that byte. 

The disassembly listing you get looks something like this: 


myprog: 

00012214 

move.1 

#$12214,al 

myprog 

0001221A 

lea.l 

$12214 (PC)', al 

myprog 

0001221E 

move.1 

al,$12004 

myvarl 

00012224 

move.1 

$12004,$12008 

myvarl; myvar2 

0001222E 

move.1 

$4BA.w,dl 

clock 

00012232 

bra.b 

$12214 

myprog 


The listing has four columns: the disassembly address is printed in 
the first column, then the opcode and size, then the operands, and 
finally any symbols matching the values used in the operands. 

If there are any symbols with the same value as the address of the 
instruction being disassembled, they are printed out above the 
disassembly line (like the label "myprog:" above). 
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The names in the right-hand column are the names of symbols matching 
the operands, separated by commas. If there are two numeric operands, 
and there is at least one symbol matching each of them, the symbols 
for each operand are separated by a semicolon. 

Operands which are less than $100 do not get matching symbols printed: 
it would be too confusing, since so many symbols lie in this range, 
and picking out the one which mattered in any particular instruction 
would be impossible for the debugger and difficult for the user. You 
can list all the symbols with a given value using the "where" command. 

In the opcode field, some liberties have been taken. If an instruc¬ 
tion can not be disassembled, the listing will show ".dc.w xxxx" where 
xxxx is the value at that address. If the instruction begins with 
SAxxx or $Fxxx, the listing will show "line-a xxx" and "line-f xxx" 
respectively. 


Examples: 

1 list 12 lines starting where the last 

1 left off 

1 main[10] list from the label "main" up to and 
including the instruction which ends 
at or after main +15 

1 'pc[l] list the instruction at the current PC 


d [ { h | 1 } ] [ range ] 

The d (dump) command dumps memory. The default start for range is the 
place where the last dump left off. The default count is 128 bytes. 
If w or 1 is specified, the command dumps words or longwords, respec¬ 
tively. If neither is present, bytes are dumped. 

The memory dump consists of lines with the starting address on the 
left, the memory bytes (or words or longs) in the middle, and the 
ASCII representation of the memory on the right. The ASCII represen¬ 
tation shows the character associated with each byte in memory, if 
that character is in the "printing character" set (32-127,160-254 on 
the Atari ST). 

The range argument is used as a guideline. If w or 1 is present, the 
last part of memory dumped will be the word or longword which contains 
the ending address of the range. Hence, dl[8] dumps two longwords, 
but so does dl[7] since the seventh byte is contained in the second 
longword. 

The d command alone, with no range or size specifier, dumps 128 bytes 
starting where the last dump left off, and in the last format used. 
The command "dlO" dumps 32 longwords starting at zero; if followed by 
simply "d" another 32 londwords will be dumped: the size specifier is 
preserved. A d command with a range will reset the size to word, 
long, or byte (if neither w nor 1 is specified). 
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Examples: 

d 

dump 

128 bytes in the last format 

dw 

dump 

64 words (128 bytes) 

dl 

dump 

32 longs (128 bytes) 

d [10] 

dump 

16 bytes 

dl 8[1] 

dump 

the bus-error exception vector 

dw 'sp 

dump 

the stack (as words) 


s [ { w 1 } ] [ addr [ va lue . . . ] ] 

s [ { w 1 } ] range value 

s addr string 

The s (set) command is used to change the contents of the client's 
memory. In the first two forms, the presence of w or 1 indicates that 
words or longwords are to be set. If neither w nor 1 is present, 
bytes are set. 

In the first form, if any values are present, the byte (or word or 
longword) at addr is set to the first value . If there are many 
values , they are placed in memory consecutively starting at addr and 
incrementing addr by the appropriate number (1, 2, or 4 bytes). 

If value is not present, memory is set interactively. A memory 
address is printed on the screen, followed by the (byte, word, or 
long) value currently there. At this point you can just hit the 
"return” key to skip to the next location, or type a new value (plus 

"return") to be placed at that address, or a single period (".") (plus 

"return") to terminate the set command. 

The second form fills the specified range with the (byte, word, or 
long) value . If the size of the range is not a multiple of the unit 

(1, 2, or 4 bytes), an extra (long)word is deposited. See the d 

(dump) command; this works the same way. 

The third form sets the memory starting at addr to the bytes 
represented by string . The string is placed in client memory as-is: 
it is not null-terminated. 

See the section STRINGS in the chapter EXPRESSIONS, RANGES, AND 
STRINGS for more information. 
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Examples: 


s 400 

set bytes interactively 
starting at $400 

si 400 

set longs interactively 
starting at $400 

sw 380[80] 1234 

Fill 128 bytes with $1234 

sw 6F0 FF20 12 0 -2 

set these words at 
6F0..6F7: FF20 0012 0000 
FFFE 

s 6F0 M Testing\r\n\x00" 

Set a C-type string 

(null-terminated) at 6F0 


f [ { w | 1 } ] range value ... 
f range string 

The f (find) command prints out the beginning address of areas of 
memory within range which match the target pattern. It also sets the 
debugger variable $ to the address of the first match. 

The first form takes a size specifier (w for word, 1 for long, or 
nothing for byte) and a sequence of values . The values are treated as 
being of the indicated size,, and are used as the target pattern for 
the find. The asterisk ("*") is a special value which will match any 
byte (or word or long): it is a wildcard. 

The second form takes a string as the target of the find. See the 
section STRINGS in the chapter EXPRESSIONS, RANGES, AND STRINGS for 
more information. 

For the find command (and only the find command), the string escape \? 
is a one-byte wildcard, which matches any byte in the client's memory. 

Note that each individual value is expanded or truncated to the size 
of the find (byte, word, or long), then split into the component 
bytes. Ultimately, the target is always a sequence of bytes. This 
means that a fw or fl command can actually find matches at odd boun¬ 
daries . 


Examples: 


fl 0,400 FC0008 
fw 'al[100] 100 * 300 

f *a7[100] "x\?z" 


Find the four bytes 00 FC 00 08 

in the range 0..3FF 

Find the six bytes 01 00 * # 03 

00 

Find the three bytes 78 * 7A 


THE CLIENT AND SYMBOLS 

These commands load the client and manage the debugger's symbol table. 
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See the chapter SYMBOLS AND DEBUGGER VARIABLES for more information. 


exec [ { program [ args ... ] | on | off } ] 

The exec command loads the named program and sets it up for execution. 
It also loads the symbols from that program , and sets the GEMDOS 
command-line arguments to args. if any. The debugger variable 
"clientbp" is set to the basepage of the loaded program. Finally, the 
basepage information of the client is displayed. 

With no arguments, exec displays the basepage information at 'clientbp 
(usually the basepage of the last-execed client). 

Normally, when a client uses Pexec and executes a child, a message is 
sent to the debugger with that child f s basepage address. The "exec 
off" command disables this. "Exec on" re-enables it. When remote 
debugging with the resident stub, this starts out disabled; you can 
enable it with "exec on" when the client is stopped (e.g. because you 
hit the stop button). 

When you start the debugger with a program argument on the command 
line, it performs an exec command with that program and any args fol¬ 
lowing it. 

When you are not remote debugging, you can use exec to load clients. 
You must exercise care, however. Once you load one client, you may 
not be able to load another. The first must either terminate or exe¬ 
cute the GEMDOS call Mshrink, to make memory available to the second 
client. Also, if you stop one client while it is in a GEMDOS trap, 
then try to use the exec command to load another client, GEMDOS will 
bomb ungracefully: it is not reentrant. See the chapter OPERATING 
SYSTEM CONSIDERATIONS for more information. 

You can't use exec to load programs when remote debugging. The first 
form still works, however, to display basepage information. 


Examples: 

exec display basepage information 

exec myprog.prg load myprog with no arguments 

exec myprog.prg -o xyz load myprog with command-line 

arguments "-o xyz" 


args [ args _ ] 

The args command sets the command-line arguments for the most recently 
exec-ed client to args. If there are no args , the command-line argu¬ 
ments in the client T s basepage are cleared out. 
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Examples: 


args 

args -0 xyz 

clear out the argument area of the client 
set the arguments area to "-0 xyz" 


getsym program [ textbase ] 

The getsym command loads symbols from the named program file. Most 
GEMDOS programs are relocatable, so you must supply the textbase argu¬ 
ment to relocate the symbols. Some programs, notably those which are 
placed in ROM, are absolute, and need no relocation. You don't need a 
textbase argument for these. 

This command is used to get symbols for a program which is already 
loaded, usually when remote debugging. Be sure that the program file 
you load symbols from is the same program file that the client was 
loaded from; otherwise, the symbol values may not match. 

When not remote debugging, do not use this command if you have stopped 
the client in the middle of executing a GEMDOS system call: this com¬ 
mand uses GEMDOS to read the file, and GEMDOS is not reentrant. See 
the chapter OPERATING SYSTEM CONSIDERATIONS for more information. 


Examples: 

getsym myprog.prg 'pc load symbols from myprog.prg, relocat¬ 
ing them by the current PC. Right 
after an exec, 'pc is the text segment 
base address of the process. 

getsym my file. rom_load symbols (absolute: no relocating) 


sym name value [ { r | a } ] 

The sym command creates a new symbol in the symbol table, 'Name and 
value are used for its name and value. With * a' or nothing after 
value , the symbol is considered absolute; with *r' after value , the 
symbol is considered relocatable, relative to the current client 
basepage ('clientbp). The new symbol will be treated just like all 
the existing symbols in the symbol table. 


nosym 

The nosym command deletes the entire symbol table. Because of the way 
the debugger stores symbols, this memory is not recoverable: if the 
symbol table took up 12K and you use the nosym command, you will sim¬ 
ply lose that 12K from the debugger's memory space for the rest of the 
session. Db will ask for verification before doing this, and will 
report that the memory was "dropped on the floor." 
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? [ symbol ] 

The ? command displays the symbol table. If a symbol argument is 
present, it lists from that symbol onward. Otherwise, it starts at 
the beginning. Use A S to pause the listing, ~Q to resume it, and ~C 
to abort. 

The symbol list consists of the symbol 1 s name, its value, and its 
type, both in hex and in English: each bit of the type has a name 
associated with it, and if that bit is set the name is printed. If 
the bit is clear no name is printed. 


Examples: 



7 

list 

the whole symbol table. 

? main 

list 

the symbol table, starting with "main" 

? .main 

same 

as above 


where [ expression ] 

The where command shows symbols with values at or before the value of 
expression . If expression is absent, the current PC is used. 

Where shows the value of expression , then lists the symbols with that 
value. If there are none, it looks for the next lower valued symbol, 
and lists all symbols with that value, with their offset from the 
expression. 

Consider the following examples, assuming that the symbols "myprog" 
and "start” have the value 12000 (hex), "main” has the value 12030 , 
and "loop” has the value 12038 . 


© 1988 Atari Corp. 


25 




DB 


ATARI DEBUGGER 


AUGUST, 1988 



COMMAND 

OUTPUT 

(a) 

where 12030 

12030 : main 

(b) 

where 12034 

12034: main + 4 

(c) 

where 12038 

12038 : loop 

(d) 

where 1203A 

1203A: loop + 2 

(e) 

where 12000 

12000: myprog, start 

(f) 

where 12006 

12006: myprog, start + 6 

Is) 

where 30040 

12FFE: loop + 1E002 

(h) 

where 0 

No symbols at or before 0. 


The last few examples need more explanation. Examples (e) and (f) show 
that two symbols with the same value will both be printed if neces¬ 
sary. Example (g) shows that the output of where is not always mean¬ 
ingful: 30040 is probably well beyond the intended scope of the label 
"loop," but since that is the symbol with the next lower value, it is 
displayed. Example (h) shows what happens when there are no symbols 
at or before the value of expression. 

The where command with no argument shows the where list for the 
current PC. This is useful when a trace/go command has stopped 
because of, say, a bus error: you can find out what procedure the PC 
is in just by typing where. 


stack 

The stack command tries to perform a stack traceback using the Alcyon 
C calling conventions. The traceback listing always starts with the 
current PC, and shows a where-type list for that location. Then the 
frame pointer (a6) and stack pointer (a7) are reloaded like an unlink 
instruction, and the new PC is taken off the stack. The new PC and a 
where-type list for it are printed, and the process repeats. 

The traceback stops when the end of the stack is reached (i.e. the new 
frame pointer is zero), or there is some error in the traceback (odd 
or zero address, etc.). 

The stack command tries to be clever: if the current instruction is 
"link," it deduces that you are at the start of a procedure, and that 
the top longword on the stack is the return PC. If the current 
instruction is "rts," it assumes that the unlk instruction has already 
executed, and, again, the top longword on the stack is the return 
address. These are not always valid assumptions, but they work well 
enough for un-optimized Alcyon C compiler output, and for most other 
compilers using the link/unlk conventions. 

If your program does not follow the C calling conventions, or follows 
them differently (e.g. using something other than a6 as the frame 
pointer), this traceback will do you no good. 
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REGISTERS AND VARIABLES 

These commands manipulate the client's registers and the debugger vari¬ 
ables . 


x [ variable [ value ] ] 

The x command alone displays the client's CPU registers: the PC, both 
stack pointers, the SR, and all the data and address registers. In 
addition, it disassembles the instruction at the PC (like l'pc[l] 
would). 

With a variable argument, x displays the value of the given variable. 
With both a variable and a value argument, variable is set to value. 

The CPU register display includes a mnemonic display of the SR. The 
mnemonics are as follows: 


su 


supervisor mode 

TR 


trace bit set 

IPL 

-X 

x is the IPL 

CS, 

cc 

carry set, clear 

ZR, 

NZ 

zero set, clear 

vs. 

VC 

overflow set, clear 

XS, 

XC 

extended carry set, clear 

MI, 

PL 

sign bit set, clear 


Examples: 



X 

show 

the CPU state 

x sr 

show 

the SR 

x sr 0700 

set 1 

the SR to 0700 (IPL 7) 

x tl 

show 

the debugger variable tl 


vars 

The vars command lists all the debugger variables. It is provided as 
a reminder. 


stubstate 

The stubstate command displays the stub variables and their values. 
See the section DEBUGGER VARIABLES in the chapter SYMBOLS AND DEBUGGER 
VARIABLES for more information. 


REMOTE DEBUGGING COMMANDS 

The following commands only have meaning when remote debugging. They do 
nothing when debugging on a single machine. See the chapter REMOTE DEBUG¬ 
GING for more information. 
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wait 

The wait command is used to synchronize the head and the stub after 
the slave machine is reset, or the terminate or continue commands are 
used, or any other time that the head is out of synch. 


check 

The check command is used to check the integrity of the connection 
between the head and the stub. It is meant for debugging the 
debugger. It presents you with a list of keys it responds to, and 
begins a feedback test. When an asterisk (’*’) appears, a successful 
turnaround has occurred. When the letter *S* appears, the head could 
not send a command to the stub. When the letter f T’ appears, the stub 
did not respond to the command. When the letter ’Z* appears, the size 
of the responding packet was not as requested. In normal debugging, 
this command is not used. 


terminate 

The terminate command causes the client program to terminate. What 
actually happens is that the stub executes the GEMDOS call Pterm, 
which terminates whatever the current GEMDOS process is. Thus, this 
can be used to terminate the client, or a child of the client. 


continue 

The continue command gives the stub a "go" command, but does not wait 
for the "go" to stop. It returns immediately to the command prompt. 
At this point, you may use any command which does not require access 
to the stub state, the stub variables, the client registers, or any 
other memory on the slave machine or interaction with the stub. Basi¬ 
cally, this means the getsym command and the expression-evaluation 
command (i.e. just type an expression at the command prompt). Two 
more commands you can use after a continue are wait, to resynch when 
the "go" stops, and quit, to leave the head while the client is still 
running. 

FILES AND ALIASES 

These commands have to do with files on the disk, aliases and other macro 
constructs, and the like. 


read [ file [ address ] ] 

The read and write commands are used to transfer data from disk to the 
client’s memory and back. The "disk" in question is always the one 
local to the head; this is not the same as the stub’s disk in a 
remote-debugging system. 

Read with no arguments displays the starting address and size of the 
last file read. With two arguments, it reads the named file into the 
client*s memory starting at the given address . 
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When not remote-debugging, a third form is allowed: with a file argu¬ 
ment but no address, read will use the operating-system call Malloc to 
allocate enough memory for the named file , then read it in to that 
memory. This is useful for patching files, because you don't care 
where it gets loaded in. Note that there must be enough memory avail¬ 
able to the operating system for the file, or the Malloc will fail. 
This is especially a problem because if you exec a program but don't 
let it return memory to the OS, it may have all free memory allocated 
to it. 


write file [ range ] 

The write command is the companion to read. With both a file and 
range argument, it writes the memory in that range to the file. With 
only a file argument, it uses the start and size information from the 
last read command. If the file already exists, the user is asked to 
verify that he wants to overwrite it. 


load file 

The load command causes debugger commands to be read from a file 
rather than from the keyboard. The file should contain normal ASCII 
text, with lines separated with CR/LF. Each line is read in and 
interpreted exactly as. if it was typed at the debuggers colon (":") 
prompt. Other input, such as verification, still comes from the key¬ 
board. 

These files are called scripts . By convention, script files (except 
for the startup files db.rc and rdb.rc) have the extension ".DB,” as 
in "SETUP.DB." 

The debugger automatically tries to load a configuration script when 
it starts up. It first looks for the file db.rc in the current direc¬ 
tory. If that is not found, it looks for SDBRC (”$F00" means "The 
string which is the value of the environment variable F00. M ). Failing 
that, it looks for "$H0ME\db.re" and after that it just gives up 
without loading any configuration script. 

A script can contain the load command itself. In this respect, load 
can be used as something of a subroutine call. No check is made for 
infinite load loops . 

Some commands are only meaningful when used in a script; they are 
goto, unload and reload. 

In a script, long commands can be split onto several lines. When a 
line in a script ends with a backslash (’V). the next line is tacked 
onto it as though it was a continuation of the same line. This is not 
the case for lines read from the keyboard. 

Example: 

print -s (lpeek ( + \ 

(lpeek (+ 'clientbp 24)) 2c)) 
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Because of the 1 \' character, the the two lines are merged into one. 
(This command prints the first environment variable in the environment 
of the parent of the current process. It is a useful exercise to 
examine exactly how it does this.) 

Long lines split with 1 \* will cause line numbers in error messages to 
be inaccurate. 


unload 

Unload causes the script currently being loaded (with the load com¬ 
mand) to end. If you think of load as a subroutine call, this can be 
used as a premature "return" statement. This amounts to a goto com¬ 
mand to the end of the script, but is faster. 

It is an error to use this command when not loading a script. 


reload 

Reload causes the script currently being loaded to be rewound to the 
beginning. It amounts to a goto to the start of the file, but is fas¬ 
ter. 

It is an error to use this command when not loading a script. 


goto label 
fgoto label 

The goto and fgoto commands change the flow of control in scripts. 
The label argument is the exact text of the line you wish to go to, 
and may only be one word. Usually, this is a comment, like "#begin" 
or "#loop." For example, consider the following text file: 

echo line 1 
xtO 0 
#begin 

print -n 'tO 

if (< 'tO 10) goto #begin 
echo 

echo end of loop 

Loading this file will cause the following output: 
line 1 

0123456789ABCDEF 
end of loop 

In conjunction with if, the goto command can be used to create very 
powerful constructs. With auto-execute aliases, the possibilities are 
virtually unlimited: a breakpoint can cause a script to be loaded, and 
with if and goto anything can happen. 

The fgoto command has the limitation that the line containing its 
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label argment must be after the current position in the script. Goto 
rewinds the file, then compares each line against the label argument, 
while fgoto does not rewind the file first. If the label is after the 
current point in the file, fgoto is faster, especially in large 
scripts. 

It is an error to use these commands outside of a script. 


alias [ name [ expansion ] ] 

The alias command lets you create your own commands which are combina¬ 
tions of other debugger commands. The easiest explanation is by exam¬ 
ple: if you use the command " alias foo dl 0[8]" and later enter the 
command ,, foo, ,f the expantion of "foo" (in this case, "dl 0[8]") will 
be executed. In other words, once you alias a name to an expansion , 
subsequent uses of that name as a command result in the expansion 
being used in its place. 

There may be several commands in an expansion — enclose the whole 
expansion in quotes, and separate the commands with semicolons, like 
this: alias show "dw .varl[2] ; dw .var2[2]" 

An alias may contain other aliases. For instance, if you alias "dump- 
word" to expand to "dw?, the above alias could be written alias show 
"dumpword .varl[2] ; dumpword .var2[2]" 

To change an alias, just redefine it with another alias command. To 
remove an alias, use unalias. 

Alias with no arguments lists all aliases. Alias with one argument 
displays the alias for that name. 

If an alias contains itself, or contains an alias which contains the 
first, an infinite loop can result. To prevent this, the debugger 
will only expand 256 aliases in one line; more than that, and it 
assumes an infinite loop has occurred and reports the fact. The 
debugger might also run out of memory for keeping track of aliases 
before this happens. 

See the chapter IF, GOTO, DEFER, AND ALIAS for more information. 


unalias name ... 

The unalias command deletes all the names from the alias list. 


noalias 

The noalias command deletes all aliases. It asks for verification 
before doing so. 
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! [ command-name [ args ... ] ] 

The I (shell) command attempts to execute its argument as a GEMDOS 
command. The first word of the argument should be the full filename 
(including the drive and path) of a GEMDOS program file (usually of 
type .PRG, .APP, .TOS, or .TTP) . When the program finishes, you will 
be returned to the debugger right where you left off, and the debugger 
will report the exit code of the program. 

With no arguments, the shell command attempts to create a shell by 
executing the file whose name is the value of the enviornment variable 
SHELL. 

Under some shells, the command-name need not be a full-blown pathname. 
See the section THE SHELL COMMAND IN DETAIL in the chapter OPERATING 
SYSTEM CONSIDERATIONS for more information. 


dir [ pathname ] 

The dir command shows a directory listing. With no pathname argument, 
it lists all files in the current directory. With a pathname argu¬ 
ment, it lists files in the directory specified by pathname . Pathname 
may end with a wildcard expression, or may consist only of a wildcard 
expression (e.g. or t, src\db??.c M ). 

Be careful of ending dir commands with a backslash ("\") in scripts: 
the trailing backslash will be taken as a continuation character, and 
the next line will be tacked onto the current one. Using, for 
instance, "A:\*.*" rather than "A:\" has the same effect and avoids 
the problem entirely. 


Examples: 

list all files in current directory 
list all files in the root of drive A 
list all files in the subdirectory 
src with extension ,f .c" (C program 
source files) 


dir 

dir A:\*.* 
dir src\*.c 


MISCELLANEOUS COMMANDS 


abort [ avgs ... ] 

The abort command prints out its arguments (usually an error message 
of some sort) exactly the same as the print command, and then it 
returns to the command prompt. Any script which was loading, or alias 
which was executing, or deferred commands which were pending are for¬ 
gotten: the debugger is reset to the very top level, and waits for 
user input. 
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The # command introduces a comment. The rest of the command is 
ignored. Target labels for the goto command also start with #, so 
they are not executed as commands. 

Note that a semicolon will still separate this command from its neigh¬ 
bors : 


# this is a comment ; echo but this is not 

will in fact display the words ,f but this is not.” If you want to use 
the semicolon in a comment, you should put quotes around the whole 
thing: 


# f, This is a comment; it contains a semicolon” 


transcript [ { file [ a ] | off | flush | printer } ] 

Transcript starts a transcript of all the output from the debugger, 
and all the input from the user. The file argument tells what file to 
keep the transcript in. When you leave the debugger for any reason 
(short of resetting the head machine) the transcript file is saved and 
closed. The command "transcript off” stops the transcript explicitly, 
and saves and closes the file. 

Transcript printer causes debugger output to go to the printer as well 
as the screen. Note that output is buffered in a transcript buffer, 
so the printer will always be slightly behind what is on the screen. 
(The buffer size might be as much as 4K.) 

Transcript flush flushes the buffered transcript information expli¬ 
citly. This is especially useful when transcrip ting to the printer, 
because otherwise recent information will not have been printed yet. 

Transcript alone tells the state of transcripting (on or off). 

The a option to the transcript file form means "append” and causes the 
transcript to be appended to the transcript file; otherwise, file is 
created and any existing file with that name is removed (without warn- 
ing) . 

The transcript command must be used carefully unless you are remote 
debugging. On a single-machine system, you should be careful not to 
stop the client while it is processing a GEMDOS call. When the tran¬ 
script buffer fills up, it needs to be flushed to disk, and this is 
done with GEMDOS calls. If the client is in the middle of a GEMDOS 
call, this will crash your system. 

Note that the only ways to stop the client while it is in GEMDOS are 
to use the u (untrace) command when at a "trap #$1” instruction, use 
the stop button, or cause a bus error or other exception in GEMDOS. 
If you avoid these conditions, transcripting should be safe even when 
debugging locally. See the chapter OPERATING SYSTEM CONSIDERATIONS for 
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more information. 


exit 

The exit command is used to terminate the stub and leave the debugger. 
Whether remote debugging or not, this command causes all machines 
involved to return to a quiet state. In a single-machine model, the 
debugger will remove itself and the stub and return to the desktop or 
shell. If you are remote debugging, the head will tell the stub to 
remove itself, then remove the communications layer from the slave, 
and finally remove the communications layer from the master. Again, 
both machines should return to the desktop or shell. 


quit 

The quit command exits the debugger. If you are remote debugging, it 
does not cause the slave to terminate or exit or even to stop. It can 
be used after a continue to let the client run while you do something 
else on the master machine. 


help 

The help command alone lists the debugger commands and the operators 
for complex expressions, and a brief reminder of what they do. 


echo [-n][-i][-] avgs ... 

The echo command writes the avgs to the debugger output device (usu¬ 
ally the screen). Each argument is written on one line, separated by 
a single space. The -n switch will suppress the newline at the end of 
the output; this can be used to concatenate the output of multiple 
echo commands. The -i switch causes the output to be in inverse 
video, like error messages from the debugger. The - switch (just a 
dash with no letter after it) is used when the avgs start with a dash: 
it means "don't try to interpret the next argument as a switch." 


Examples: 


echo 

echo -i Error 
echo -n Error 
echo -i -n Error 
echo - -foo- 


echo nothing plus a newline to the output device 
echo the word "Error" in inverse video 
echo the word "Error" with no newline after it 
echo Error in inverse with no newline 
echo the word -foo-. Note that "echo -foo-" 
wouldn't work, because echo would try to inter¬ 
pret "-f" as a switch. 


print avgs ... 

The print command is very like the echo command, except that it does 
not simply write its arguments out: it evaluates them, and those that 
evaluate to a number print as the value, not the text: "echo (+ 2 5)” 
displays "(+ 2 5)" while "print (+ 2 5)” displays "7." 
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Those arguments which do not evaluate to a number get printed as they 
stand, so "print basepage = 'clientbp" displays the word "basepage" 
and the equals sign, and then the value of the expression 'clientbp. 

The format of the displayed numbers can be set with switches within 
the print command. The switches are as follows: 



PRINT COMMAND SWITCHES 

SWITCH 

MEANING 

“X 

Set output radix to hex 

-d 

Set output radix to decimal 

-0 

Set output radix to octal 

-b 

Set output radix to binary 

-x4 

Set output radix to hex, and use at least 4 spaces 
The number 3A would print as " 3A" 

(Works for other radixes, too.) 

-x08 

Set output radix to hex, use 8 spaces, and zero- 
fill the 8-space field. The number 13A3E would 
print as 00013A3E. (Works for other radixes, 
too.) 

-s 

String; see below. 


The ’-s’ switch causes arguments which evaluate to numbers to display 
the string at that address in the stub's memory, as ASCII characters, 
up to the first zero byte. A number, like '-s9', causes the string to 
be at least that many characters wide, and to be left-justified in the 
field. A leading zero and a number, like '-s09,' causes the string to 
be at least that wide, and to be right-justified in the field. 


if predicate command 

The if command works as you might expect: if predicate evaluates to 
TRUE (nonzero), the command is executed with its args. If predicate 
is FALSE (zero), command is not executed. 

The tail of an if command can be several commands separated by semi¬ 
colons, in the same way that an alias can be several commands: if the 
command argument is enclosed in quotes (single or double), it may con¬ 
tain several commands. See the chapter IF, GOTO, DEFER, AND ALIAS for 
more information. 


Examples: 


if (= 'dO 0) echo dO is zero. 

Simple condition. 

if (< 't0 10) goto #begin 

Part of a loop in a script. 

if (= (wpeek 'sp) 1) \ 


"print (lpeek (+ 'sp 2));defer g" 

See below. 


The last example above might be an auto-execute alias for a break¬ 
point: if the word at the top of the stack is 1 when the breakpoint is 
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hit, the longword on the stack after that is printed and the client is 
allowed to start up again. Note the compound command, with the semi¬ 
colon protected by quotes, and the use of defer to start the client 
the next time the debugger would normally display the prompt. 


indirect addv 

The indirect command causes the client memory starting at the address 
exp to be read into a local buffer and excecuted as if it was typed at 
the command prompt. The command ends with a zero byte. 

EXAMPLE: 

s .buf "echo hello\xOO ff ; indirect .buf 

This example sets the string M echo hello" (plus a zero byte) into the 
client memory, then executes the command at that address. Obviously, 
it prints the word "hello" on the screen. 
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CHAPTER 5 


THE CLIENT, BREAKPOINTS AND CHECKPOINTS: DETAIL 


This chapter goes into more detail concerning the client, breakpoints, and 
checkpoints. 


THE CLIENT’S MEMORY 

The client’s memory is accessed by the debugger in chunks of anywhere from 
one byte up to one kilobyte. As a rule, when the head wants to examine 
the client’s memory, it asks the stub to copy some into a buffer and send 
it over. Such copying is done as bytes, to avoid address errors. 

However, sometimes the head asks for exactly two or four bytes. In these 
cases, the move.w or move.l instruction will be used. This means that 
word-addressed I/O registers will behave as expected. It also means that 
odd addresses in these cases will -cause address errors. 

The following commands show some times when this happens: 


Command 

Comments 

dwaddr[l] 

Dumps exactly one word. 

dwaddr[2] 

Also dumps one word (the number in brackets 
is always the number of bytes in question, 
not the number of "things”). 

si addr 

Begins interactively setting longwords. 

(By reading and writing them them as longs.) 

(wpeek addr) 

Both wpeek and lpeek act this way. 

maddr.w != { addr2 } 

The operands of a comparison memory check 
are read as words or longs, as appropriate. 


The f (find) command always treats the thing you are looking for as a 
stream of bytes, so words and longs don’t have meaning. The indirect com¬ 
mand, the special message type FOxx, and the -s form of print also read 
client memory in chunks, not as words or longs. 

Dumps (even dw) and sets (even sw) of a total number of bytes other than 2 
or 4 will use byte moves, and a dw or sw of two words will use a long 
move. 


TRACE AND UNTRACE 

Trace and untrace are really two modes of the same command. They both 
single-step through the client. The difference is that trace mode treats 
instructions which cause traps specially, while untrace mode does not. 
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Instructions which cause traps are: TRAP, TRAPV, line-A ($Axxx), and 
line-F ($Fxxx). 

If the PC is at a trap instruction and you use the t command, the result 
will be that the trap instruction (and therefore the trap handler) will be 
executed at full speed. When you next see the prompt, the PC will at the 
instruction after the trap. 

If you use the u command in the same situation, only the trap instruction 
itself will be executed, not the whole handler. When you see the prompt, 
the PC will be at the first instruction of the trap handler, and the 
supervisor stack will hold the trap exception frame. 

Trace mode treats the trap instruction specially so you don't have to 
worry about stopping the client in the middle of the operating system, and 
so the OS will execute at full speed. This way you can set memory check¬ 
points and then say tx to trace through your program forever, with an 
opportunity between each instruction, but without slowing down OS calls 
and without the possibility that you will stop in the middle of the OS 
itself (which is deadly when not remote debugging). Untrace mode is pro¬ 
vided so you can debug the trap handler itself. 

The verbose-trace command is like trace: it executes a trap handler as 
though it were one instruction. 


MESSAGES 

A message is a special type of communication from the client to the head. 
Messages don't come from the stub; they come from the client itself, or 
from another part of the debugger. For instance, when you use the exec 
command, a message is sent telling the head the basepage address of the 
program that was loaded. If the load fails, or the client later ter¬ 
minates, another message is sent to inform the head (and hence the user) 
of this, too. 

A program being debugged can send messages, too. Messages consist of a 
16-bit message number and a 32-bit message argument vector. The negative 
message numbers are reserved for use by the debugger, but a client may use 
the positive message numbers freely. A client sends a message to the head 
as follows (in C): 


xbios(ll,5tfflsg_number,msg_argv); 

Msg_number is a l6-bit integer and msg_argv is 32 bits (e.g. a pointer or 
a long integer). 

Remember, negative message numbers are reserved for the debugger's use. 
When a message is received by the head with a positive message number, the 
message number and argument vector are displayed, and the client is 
stopped. See the section AUTO-EXECUTE ALIASES in the chapter IF, GOTO, 
DEFER, AND ALIAS for more on what happens when messages arrive. 
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Note that messages provide an opportunity as well as a stop when they hap¬ 
pen during a trace/go* 

Message types in the range SFOOO to SFOFF are special: they are commands 
from the client to print something on the user’s screen. The message 
argument vector holds the starting address of the (ASCII) text to display, 
and the lower byte of the message number holds the length of the text. If 
the lower byte is zero (that is, message number SFOOO), the debugger 
prints the text up to the first null byte. This means that you can print 
some text on the debugger’s output (and cause an opportunity and a stop) 
with the following line (in C): 

xbios(11,5,OxfOOO,"This is my message”); 

Some C macros such as the following would be useful: 

#define DBMSG(msgnum,msgargv) xbios(11,5* msgnum,msgargv) 

#define DBTEXT(s) DBMSG(OxfOOO,s) 

Debugger messages can be used from any language which gives access to the 
Atari ST’s XBIOS. Note that the stub itself masquerades as XBIOS function 
code 11 (decimal); do not use this call for anything but sending messages. 


BREAKPOINTS IN DETAIL 

Breakpoints work internally as follows: When a trace/go is started, the 
instruction at each breakpoint address is saved, and the ILLEGAL instruc¬ 
tion is placed at those addresses. Then the client is started. If the 
processor comes across an ILLEGAL instruction, it generates an exception, 
which the stub catches. It checks to see if the address of the illegal 
instruction matches any of the breakpoints that were set. If so, the count 
value of the breakpoint is decremented (but not through zero) . If the 
result is zero, the trace/go stops and all the instructions with break¬ 
points are restored to their original values. Otherwise, the trace/go 
continues, starting with the instruction which was "under” the breakpoint 
(i.e. the one replaced by the ILLEGAL instruction). 

MEMORY CHECKPOINTS IN DETAIL 

Checkpoints have two phases: the initialization phase and the evaluation 
phase. The initialization phase occurs when the head tells the stub to 
begin a trace or go. The evaluation occurs during opportunities such as 
between instructions of a trace and while processing a breakpoint. 


Comparison checkpoints 

If the old keyword was used in setting the checkpoint, the value at 
the address is read into the operand field as the first part of the 
initialization. Then, all comparison checkpoints are evaluated once, 
and their current state (true or false) is saved. 
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When a comparison checkpoint is evaluated, its state (true or false) 
is computed again. If it’s the same as the old state, there’s no 
stop. If the old state was TRUE and the new state is FALSE, the new 
state is saved. If the old state was FALSE and the new state is TRUE 
(i.e. the comparison has become true), the checkpoint causes a stop. 


Range checkpoints 

Range checkpoints are initialized by computing the CRC value for the 
region in question. That value (16 bits) is stored in the checkpoint 
slot. When an opportunity arises, the CRC is computed again. If it 
doesn’t match the initial value, the checkpoint causes a stop. 

Note that the CRC is not an infallible method for detecting changes. 
Some changes can cause the region to compute the same CRC value as 
before. 


MEMORY CHECKPOINTS ON VALUES IN REGISTERS 

With the ampersand prefix (e.g. &dl) you can get the address where the 
stub stores the values of CPU registers during checkpoint evaluation. 
What you have to realize is that the address you get is the address of the 
high-order byte of the value. For memory checks on dl.l, then, ”&dl.l” is 
the correct address specification for the m command. If you want to per¬ 
form your memory check on dl.w, ”(+ &dl 2).w" is the address expression 
you want. For dl.b, ’*(+ &dl 3)-h” is what you would use. 

To compare two registers to each other, you would use the indirect com¬ 
parison checkpoint type. Say you want to stop when al.l is greater than 
a2.1: the command ”m tal.l > {&a2}” accomplishes this. Of course, to com¬ 
pare words, you have to shift the addresses by two: ”m (+ &dl 2).w > 
{(+ &d2 2)}" stops when dl.w > d2.w. 

It is also important to remember that not all CPU registers are longs: the 
SR is stored as a word, so ”&sr.w” is the address for the whole SR, and 
"(+ &sr l).b” is the address for the CCR part of the SR. See the section 
Stub Variables in the chapter SYMBOLS AND DEBUGGER VARIABLES for a com¬ 
plete list of stub variables. 
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SYMBOLS AND DEBUGGER VARIABLES 


Db can load symbols from programs and other sources. In addition, the syra 
command can be used to create entries in the symbol table to assist debugging. 
Debugger variables are values the debugger makes available to the user by 
name, such as the basepage of the program last loaded, and the type and argu¬ 
ment vector of the last message, along with eight temporary storage locations 
for use at the user’s whim. 


SYMBOLS 

Symbols are loaded from programs being debugged using the exec and getsym 
commands. These commands add the symbols from the files they load to the 
debugger’s internal symbol table. The value of a symbol in the table can 
be used in an expression by prefixing it with a dot: f .symx f yields the 
number in the value field of the symbol ’symx’. 

Symbols which refer to addresses in the text, data, or BSS segments of a 
program are relocatable symbols. In the program file, they have values as 
though the program were running from absolute address zero. Of course, 
programs don’t run there, so the program loader (and the debugger) must 
relocate the values of these symbols to reflect the address at which the 
program is actually loaded. Db takes care of this automatically. 

A program file may have been produced by linking several modules together. 
These modules each had some global symbols and some local symbols. If you 
ask it to, your linker will include either both kinds of symbols, just the 
global symbols, or no symbols in the program file. Global symbol names 
are usually unique in a program file, but local symbol names might not be: 
there might be a local symbol called ’’start” in both ’’filea” and ’’fileb,” 
for instance. 

If you have aln or another linker following the same conventions, you can 
specify the file name before the symbol name to differentiate these two: 

’.filea:start’ is different from ’.fileb:start’. If fileb came from the 
library (archive) mylib, the full specification is ’ .mylib:fileb:start’. 
Furthermore, there is something called a ’’confined” symbol: a symbol whose 
scope extends to the two unconfined symbols surrounding it. These symbols 
begin with ’.’, ’~’, and ’ L ’. 

(Symbols beginning with ’L* are generated by some compilers (notably 
Alcyon C) as internal labels. Strictly speaking, they are not confined: 
they are unique within each source file. However, they are considered 
confined so when their full specification is printed by the debugger, you 
can see what procedure they occur within.) 

In general, symbols are uniquely identified by the names of all the levels 
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enclosing them: the levels of enclosure are archives, files, uncon¬ 

strained symbols, and constrained symbols. 

Take the following code fragment, for example: 


; file init.s in archive mylib 


clrmem: 


move.w 
move. 1 

.loop: clr.b 
dbra 


#COUNT-l,dO 
#START,aO 
(a0) + 
dO,.loop 


The full specification of the symbol .loop is: 


. mylib:init:clrmem:.loop 


Be careful to distinguish between the period which introduces a symbol 
specification and the period which is the first character of a symbol's 
name. If this .loop is the only one in the symbol table, it could be 
specified simply as "..loop". 


Still another way to differentiate symbols, useful for files linked 
without symbols of type 'file' - , is the number-sign ('#'). ".symx#4" 
refers the fourth occurance of symx in the symbol table. 

Finally, if you specify ".main" and there is no symbol main in the symbol 
table, but there is a _main, the debugger assumes the leading underscore 
for you. Specifically, if the symbol you request doesn't exist and 
doesn't start with an underscore, the debugger prepends an underscore and 
looks again. If that symbol doesn't exist either, the debugger appends an 
underscore, because this is Mark Williams C's convention. 


DEBUGGER VARIABLES 

The debugger variables carry information which you can read, change, and 
use in expressions. You can see the names of all the variables with the 
vars command, you can see or set a variable with the x command, and you 
can use the value in an expression with the backquote (''*) prefix. 
Finally, you can get the address of the stub variables with the ampersand 
('&’) prefix. The stub variables are special because their true values 
come from the stub. A copy of these variables is kept in the head, and 
when you trace or go, they are written to the stub. When the trace/go 
finishes, their (possibly changed) values are read back from the stub. 

(In fact, the true values of all of the stub variables is read from the 
stub when first you read or set any of them. If you change a variable, 
the new values are all written to the stub the next time you trace or go. 
This saves time when you don't read or set them. The breakpoint and 
checkpoint arrays work the same way, but they are managed by their own 
commands.) 
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All debugger variables are stored as a longword in the head, and most are 
stored as a longword on the stub. The ones stored as words on the stub 
have " (word)" after them in the following table. To use these in a 
comparison-type memory checkpoint, you would use, for example, "&sr.w" to 
refer to the status register. 


Stub Variables 

The Stub Variables contain information about the stub. 


NAME 

DESCRIPTION 


cputype 

The type of CPU the stub is on (68xxx, 

word) 

version 

The version number of the stub (word) 


nbreaks 

The number of breakpoint slots (word) 


nmems 

The number of memory checkpoint slots 

(word) 

stubcode 

Pointer to the start of the stub 


breakptr 

Pointer to the breakpoint array 


memptr 

Pointer to the memory checkpoint array 


stubbp 

Basepage address of the stub process 
symbols) 

(for 

clientbp 

Basepage address of the last-exec r ed client 


Client Registers 

The Client Register variables are the ones which mirror the actual CPU 
registers of the client. 


NAME(S) DESCRIPTION 


sr 

dO - d7 
aO - a6 
ssp 
usp 
pc 

msp vbr 
isp 
a7 sp 


sfc dfc cacr 


caar 


The status register (word) 

The data registers 
The address registers 
The supervisor stack pointer 
JThe user stack pointer 
The program counter 
680 x0 registers (unused, words) 

Translated to usp or ssp based 
on sr 


Local Variables 

The Local Variables are not stored in the stub. They are provided for 
temporary storage and to remember information like the last message 
type and argument vector, or the first match of the last find command. 
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NAME(S) 

DESCRIPTION 

t- 

-p 

1 

0 

■P 

Eight temporary variables you can use 
however you like 

$ 

The "last" register: holds the value of 
the last expression 

mtype 

The type of the last message received 
from the client 

margv 

The argument vector from the last message 
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IF, GOTO, DEFER, AND ALIAS 


This chapter describes the if, goto, defer, and alias commands, and offers 
some advanced advice on using the debugger. 

It is unfortunate but true that you may have to read this whole section before 
you can really understand and use any of it. The explanations of alias, 
defer, and compound commands are of necessity given in terms of each other. 
Please be patient and read through this a couple of times. 


IF 


The if command takes two arguments: an expression and a command. If the 
expression evaluates to something nonzero, the command is executed. This 
allows some powerful flow-control in conjunction with commands like load, 
unload, rewind, defer, and especially goto. 


GOTO 


The goto (and fgoto) commands are used in files being loaded (called 
"script" files). They cause control to pass to another place in the 
script. The argument to a goto command is a label , which is usually just 
a comment, like "#begin." The goto command rewinds the script and looks 
for a line containing exactly (and only) the text of the label . The fgoto 
command doesn't rewind the script first, meaning it will only find the 
label if it occurs later in the script. This is slightly faster than 
goto, especially in large script files. The following example (taken from 
the description of the goto command in the chapter COMMANDS) illustrates: 

echo line 1 
xtO 0 
#begin 

print -n 'tO 

if (< 'tO 10) goto #begin 
echo 

echo end of loop 

Loading this script will cause the following output: 
line 1 

0123456789ABCDEF 
end of loop 

It is an error to use the goto or fgoto command outside of a script. 
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ALIAS 

The alias commands takes two arguments: a name, and an expansion for that 
name. After this, any time the name appears as a command, it is replaced 
(textually) with the expansion. 

(In the examples in this chapter, a line beginning with a colon 
shows a command which you can type in to the debugger. The colon itself 
should not be typed: it represents the debuggers prompt.) 

: alias foo dw.table[10] 

After using the above command to define an alias for "foo" the "command" 
foo can be used, and it will expand to "dw. table[10]" (which dumps the 16 
bytes starting at the label "table" as words). This is a very simple 
example of the alias command, but still quite useful to save time for 
repetitious commands. 

Aliases are expanded in place in the command line, and any arguments to 
the alias appear at the end of the expansion. The following (extremely 
useful) alias illustrates this: 

: alias rwfind f'rwstart['rwsize] 

After this, the new "command" rwfind can be used to find values or text in 
the file which has just been read with the read command: 
"rwfind * some text*" expands to the command 

"f'rwstart['rwsize] 'some text’" which will find all occurrances of the 
quoted text in the file. 


AUTO-EXECUTE ALIASES 

Auto-execute aliases have special names: they start with the letters 
"br" or "me" or "msg" and they are executed when a corresponding 
breakpoint, memory checkpoint, or message event happens, respectively. 
For example, when the breakpoint in slot zero causes a stop, the 
debugger looks for an alias called "brO" and executes it if it exists. 

Breakpoint aliases start with "br" and end with the slot number they 
are attached to (as one upper-case hex digit): brO through brF if 
there are 16 breakpoint slots. Memory checkpoint aliases start with 
me and end with the memory checkpoint slot number, also as one upper¬ 
case hex digit. Message checkpoints start with msg and end with the 
message number they handle, as four upper-case hex digits: msgOOOO for 
message type zero, msgOFCA for message type SOfca. 

When several events happen at the same time, such as multiple check¬ 
points or a checkpoint and a breakpoint, only one auto-execute alias 
is executed. Breakpoint aliases are checked for first (in ascending 
numerical order), then checkpoints (also in order), and finally mes¬ 
sages. The first one of these which exists, and only that one, is 
executed. 
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If none of these exists, the default action is taken: the breakpoint, 
checkpoint, and message type and vector are displayed on the screen. 

Note that the auto-execute alias for an event can itself cause a 
trace/go. If it does, and that trace/go is stopped by an event, the 
auto-execute aliases are checked again and the first matching one is 
executed, so the right combination of events and auto-execute aliases 
can cause a lot to happen automatically. See the examples below for 
more. 

When you set an auto-execute alias, be careful to remember that it is 
there. For instance, if you set a breakpoint someplace, and create an 
auto-execute alias for that breakpoint, and then you remove the break¬ 
point, the auto-execute alias is still there. If you set another 
breakpoint and it happens to go in the same slot as the first one, the 
auto-execute alias will be triggered by it, probably resulting in 
something you didn't expect or want. Unalias is the command which 
removes one or more aliases from the debugger's alias table. 


COMPOUND COMMANDS, introduced 

If you enclose the expansion.argument to alias (or defer or if) in quota¬ 
tion marks, it can contain more than one command: 

: alias foo "echo xtable;dw.xtable[10];echo ytable;dw.ytable[10]" 

Now, when you use foo, four commands (two echoes and two dumps) will be 
executed. Again, this can be a great timesaver. As explained below, it 
can be the key to really powerful macros. 


DEFER 

The defer command takes one argument: a command to be executed the next 
time the debugger returns to the top level for user input. That is, when 
the debugger is about to print its prompt, the last thing it does is exe¬ 
cute any deferred command. The purpose of this is to allow for automatic 
execution of the client and looping in macros, without using the alias 
stack. 

Only the last defer command is remembered. Defer with no arguments causes 
the debugger to forget any existing deferred command. 

Here is an example of the use of the defer command: 

: b.endloop 
: m &d7.1 != old 

: alias mcO "print dj changed: new value 'd7;defer tx" 

: tx 

If the client is about to start a loop, and the user wishes to be notified 
when d7 changes, the above sequence will do the trick. It will stop with 
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the breakpoint at the end of the loop, and each time d7 changes the auto¬ 
execute alias mcO will be executed. This alias displays the new value of 
d7. then tells the client to continue executing rather than returning to 
the command level. 

The above example would still work if the last command in the alias were 
simply tx rather than defer tx, but it would soon fill up available memory 
with the stacking of alias expansions: using one alias in another amounts 
to a procedure call. 

Defer can also be used as a trick to allow arguments to an alias. Remember 
that an alias expands from a command (like mwc or rwfind) into the expan¬ 
sion text, in place. Any arguments to the alias are tacked on after the 
expansion: 


: alias foo "echo one two" 

would cause "foo x y z" to expand to "echo one two x y z." A macro to 
print the Nth longword in a table starting at .table might be as follows: 

: alias nthlong "defer print (lpeek (+ .table (* 'tO 4)));xt0" 

: nthlong 3 

This works because the command nthlong is substituted with the text of the 
alias, and the '3' is tacked to the end of that. Because of the defer, 
the command "xtO 3" will be executed before the print command, so tO will 
have the value 3 by then, and the value at (.table + (3 * 4)) gets 
printed. 


COMPOUND COMMANDS, explained 

As you can see from the examples above, the if, defer, and alias commands 
each take a command as an argument. That argument can be a compound com¬ 
mand consisting of more than one simple command if it is enclosed in quo¬ 
tation marks: 

alias mycmd "echo start mycmd;l;print end of mycmd" 

Executing the above command, then the command "mycmd," will cause the 
legend "start mycmd" to appear, then a disassembly listing of 12 lines 
starting at the current disassembly pointer, then the legend "end of 
mycmd." (Sure, it's silly, but it's just an example.) 

The important point is that the semicolons are enclosed in quotes, making 
them part of the argument to "alias" rather than being interpreted as 
separating the alias command from the 1 and the print command. Without 
quotes, 

alias mycmd echo start mycmd;1;print end of mycmd 

the alias for mycmd would be "echo start mycmd" — the echo command stops 
with the first semicolon, and the 1 and print commands are executed in 
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turn. 

The alias for Mark Williams C argument string handling uses this trick: 
the alias itself consists of two commands, a find (f) and a set (s): 

: alias mwc *f (lpeek ( + 'clientbp 2c))[800] H ARGV=” ; s $ 5& f 

Note the use of single quotes around the alias, and double quotes around 
the string argument to the find command. Single quotes match single 
quotes and double matches double, but their interpretations are identical. 

You can nest these expansions: 

alias setbp "b #2 .mainloop;alias br2 ’echo loop;dw.table[10];defer g’” 

Once you create this alias, the command setbp will cause a breakpoint to 
be set, and an alias to be created which will get executed when that 
breakpoint is hit (see the section AUTO-EXECUTE ALIASES). The alias which 
setbp creates, called br2 (to attach it to breakpoint slot 2), contains a 
compound command as its expansion: the compound command prints a message, 
dumps the first eight words of a table (16 bytes), and then lets the pro¬ 
gram continue executing. 

(Unfortunately, you can’t nest more than two levels of compound commands, 
because only the single- and double-quote characters protect semicolons, 
and any more of them would look like closing, not opening, quotes.) 

Another use for auto-execute aliases might be to show something on the 
screen at the start and end of a certain procedure: 

: b #3 .myproc 

: alias br3 "echo entering myproc ; defer g” 

: fl .myproc[800] 4e5e4e75 
: b #4 $ 

: alias br4 ’’print myproc returns 'd0 ; defer g” 

Note the f (find) command in this sequence: it searches from the start of 
the procedure, for 2K bytes, for the longword $4e5e4e75* That is two 
68000 opcodes: UNLK and RTS. Every procedure compiled with Alcyon C ends 
with these two instructions, and the likelihood of finding that exact byte 
pattern anywhere in the procedure except the end is very small, so the 

chances are that breakpoint #4 will be set at the UNLK instruction. (If 
the procedure Is more than 2K bytes long, the find should have a longer 
count.) 

Unfortunately, the find will dump the locations of all matches on the 

screen, even though all we are interested in is getting $ set to the 

address of the first one. This is just one of the limitations of db’s 

macro language as it stands. 


© 1988 Atari Corp. 


49 




DB 


ATARI DEBUGGER 


AUGUST, 1988 


50 


© 1988 Atari Corp. 


CHAPTER 8 


OPERATING SYSTEM CONSIDERATIONS 


Db must operate within the constraints imposed by the Atari ST operating sys¬ 
tem. When these constraints prevent using db in the manner needed, the user 
should consider remote debugging . See the chapter REMOTE DEBUGGING for more 
information. 


DB AND GEMDOS 

When you don't specify a command-line option like -s or -m for input and 
output, the debugger uses GEMDOS to access the screen and keyboard. It is 
important to know, then, that two programs can't be using GEMDOS at the 
same time. If you stop the client while it is executing a GEMDOS system 
call (like Fopen or Cconout), and the debugger uses GEMDOS to print to the 
screen, GEMDOS will lose track of the client, and the next g command will 
create havoc. 

If you use the t, v, and g (trace, verbose-trace, and go) commands 
exclusively, there should be no problem, because they will never stop 
while the PC is in GEMDOS. However, if you use the u (untrace) command, 
you could stop while in GEMDOS, and that would be bad news. 

Furthermore, if the debugger is using GEMDOS for input and output, and you 
hit the STOP button while the PC is in GEMDOS, you are in the same boat. 
So the lesson is to use t, v, and g exclusively when using GEMDOS for 
input and output, and don't use the stop button unless you are sure the PC 
is not in GEMDOS or the BIOS. 

Even when it's not using GEMDOS for its input and output, the debugger 
uses GEMDOS for certain commands, exec (to load a file and set it up for 
execution) and getsym (to load symbols from a file). Thus, you should be 
sure that the client is not in the middle of GEMDOS when using these com¬ 
mands. Another command which can cause even more trouble is transcript, 
because the user has no control over when the buffer will be written to 
disk. When debugging locally, use transcript with extreme care, making 
sure that you don't stop while the PC is in GEMDOS. 

When remote debugging, none of this applies, because the slave and the 
master have two independent GEMDOSes. 


DB AND MARK WILLIAMS C 

Mark Williams Ct uses a different symbol table format from Alcyon's. 
tMark Williams C is a trademark of Mark Williams Company. 
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Notably, symbols are stored in 16 characters, not just 8. Also, global 
variables in C get an underscore character appended to them, rather than 
prepended as is the convention among most C compilers. (The reason for 
doing this is so you don't have to worry about name collisions with assem¬ 
bly language: by not using a leading underscore (or trailing, in the case 
of MWC), you know you won't be using the same name as a C variable.) Db 
correctly interprets Mark Williams C symbol tables, both in the old 
(before verison 3-0) and version 3*0 formats. 

Mark Williams C and some other environments use a trick to pass more than 
127 characters' worth of command-line arguments to their programs. The 
trick is to use the environment variable ARGV, because the value of an 
environment variable can be any length at all. There is a problem with 
this approach, however: since the environment is inherited from one pro¬ 
cess to another, the child can't tell if the ARGV in its environment 
really came from its parent. MWC programs will take the debugger's argu¬ 
ments as their own. 

The way to fix this is to force the MWC program to think that there are no 
arguments in its environment. There is an automatic way to do this: place 
this alias command in your db.rc file and use it after you exec an MWC 
program, but before the first trace/go command: 

alias mwc 'f (lpeek (+ 'clientbp 2c))[800] "ARGV=" ; s $ 5a' 

This alias searches in the client's environment (the address of which is 
at 'clientbp+$2c) for the word "ARGV=" and changes the first letter of 
that word to a 'Z'. This prevents the client from finding "ARGV=" in its 
environment (because it now reads "ZRGV=") and the program will therefore 
look in the basepage command line for arguments. 

If you don't understand this whole discussion, or why the alias above 
works, that's okay: just place the alias in your autoload file db.rc, and 
type the command "mwc" after you exey a MWC client. 


THE SHELL COMMAND IN DETAIL 

The ! (shell) command can be used to leave the debugger temporarily, exe¬ 
cute a command, and re-enter the debugger where you left off. What it 
does is execute its argument as a command, with the GEMDOS Pexec function. 
This requires that there be enough memory available to the operating sys¬ 
tem to run that program. This is often not the case; if you try it and 
get "insufficient memory" then that is the problem. 

Some shells use the system variable p_shell in a special way. Db tries to 
detect these shells. In the first production release, the Gulam, Craft, 
and Mark Williams shells use this. The presence of such a shell lets you 
pass p_shell a command line like "emacs foo" and let the shell figure out 
where to find emacs, how to load it, and how to pass "foo" as its argu¬ 
ment. 

You tell the debugger that you have such a shell by setting the 
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environment variable P_SHELL to the value "yes" before starting db. In 
most shells, the command to do this is 

'setenv P__SHELL yes' or *setenv P_SHELL=yes t 

With no arguments, the ! command looks in your environemnt for the vari¬ 
able SHELL. If it’s found, the value is assumed to be the full' filename, 
including the path and file type, of your shell, and that file is exe¬ 
cuted. 

When the program you execute (or the shell from SSHELL) exits, you re¬ 
enter the debugger exactly where you left off, with all the same state you 
had before you left. 

Note that this command will only work when it is okay to make GEMDOS 
calls. See the section DB AND GEMDOS in the chapter OPERATING SYSTEM CON¬ 
SIDERATIONS for more information. 


EXCEPTIONS 

The trace/go commands can all cause the program being debugged to execute 
instructions which cause exceptions in the 68000 processor. Most of these 
exceptions are caught by the debugger. In partucular, bus error, address 
error, etc. (exception numbers 2 through 9 ) are caught, as well as the 
spurious and uninitialized interrupt vectors. In addition, the debugger 
has a provision for a "stop button:" hitting the stop button will cause 
the client to stop. See the section STOP BUTTONS in the chapter REMOTE 
DEBUGGING for more information. 

The debugger contains a list of those exception vectors which it might 
take over. Initially, it goes through that list, and determines whether 
that vector is currently in use or not. A vector is considered "not in 
use" if its high byte is nonzero. This is because the "bomb handler" in 
the Atari ST uses the upper byte as the exception number. If the upper 
byte of the vector is zero, the debugger does not take it over. Note that 
the debugger restores all the vectors it takes over on exit. 

When a trace/go command causes one of these exceptions to occur, execution 
is immediately stopped and control is returned to the debugger. The pc 
and sr are saved from the exception stack frame, and all other registers 
keep their values. Note that after bus error and address error, the pc 
will not have a reliable value: the instruction causing the exception is 
near the pc, probably two to ten bytes before it. 

When a trace/go command stops because of an exception, the where command 
is convenient to determine what procedure was executing at the time: it 
reports name of the symbol closest to, but not after, the current pc. 
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CHAPTER 9 


REMOTE DEBUGGING 


You can use db as a remote debugger. This means that you can have the main 
body of the debugger (the head) on one machine (the master), and a little bit 
of the debugger (the stub) plus the program you are debugging (the client) on 
another machine (the slave ). 

The advantages are that the debugger doesn't use up the slave's memory and 
other resources (screen, keyboard, disk), and the program being tested doesn't 
put the debugger machine (presumably the one with all your files on the hard 
disk) at risk. Also, there are no restrictions in terms of GEMDOS use between 
the client and the debugger, since there are two machines and two GEMDOSes. 
Finally, you can use the debugger to debug an operating system: on one 
machine, you would need a working GEMDOS to load the debugger, but when remote 
debugging you can actually debug the OS as it boots, and you can set break¬ 
points in interrupt handlers. 

To use remote debugging, you have to load the stub into the slave machine. 
There are two ways to do this: you can start a program containing the stub 
which initializes itself and then loads your client program, or you can 
arrange for the stub to be resident in the machine and then load the client 
the way you do any other program. 

In both cases, you run the remote debugger head, rdb, on the master machine. 

The first method involves using the program "STUB.TTP" on the slave. This pro¬ 
gram takes the name of the client (and any arguments to it) as command-line 
arguments, loads the stub, then loads the client. When the client is loaded 
and ready, the stub sends a message to the head. Then, you debug the client 
as usual. When the client terminates, the stub sends another message to the 
head. If you use the exit command on the head, the stub will be told to exit 
as well. It terminates the client, unloads the stub, and both machines will 
return to the desktop or shell. 

The second method requires that you establish a resident stub. This can be 
done by running a "terminate and stay resident" program (called "STUBRES.PRG") 
on the slave machine. 

When remote debugging using the resident stub, you will not get messages when 
programs start up. In all other respects, the stub is active (i.e. it still 
informs the head of bus errors, etc.). You have to stop the slave (with the 
stop button) and explicitly enable client-startup reporting with the command 

exec on. 

When remote debugging, the normal cycle is like this: The user starts Brdb on 
the master machine, then starts the client on the slave machine, either with 
STUB.TTP or after exectuing STUBRES.PRG. The head simply waits for the first 
activity from the stub. 
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Eventually, the stub sends a message to the head (e.g. CLIENT, STOP BUTTON, 
BUS ERROR) and waits for the head to send it instructions. In response to 
commands from the user, the head sends instructions to the stub (e.g. a user 
command "dump” means the head has to ask for the contents of the client's 
memory from the stub). When the head sends a command to the stub, it waits 
for the reply before doing anything else. Usually, the replies come quickly: 
a one-instruction trace, for instance, takes only a fraction of a millisecond 
to execute. When the reply comes, the head can continue its business. 

On the other hand, the reply may be a long time away, or may never come: con¬ 
sider a g (go) command which leads the client into an infinite loop. The 
reply will never come, and the head would be waiting forever to find out what 
the result of the "go" was. 

For this reason, the debugger does not wait forever for trace/go commands to 
finish. After about 10 seconds, the message "Waiting... Press ~C to stop 
waiting." appears. The head goes on waiting for the stub to respond, but if 
you hit ~C (control-C) , the head will stop waiting and return you to the 
prompt. The client is still running, and the effect is like a continue com¬ 
mand. 

The continue command causes the head to tell the stub to run the client like a 
"go" command, but it doesn't wait for a reply . 

When the slave is busy running the client, either because of a continue com¬ 
mand or because a go command didn't reply and was stopped with ~C, the 
debugger returns you to the command prompt. You can continue issuing debugger 
commands. Naturally, since the slave is busy running the client, you can't 
issue any commands which need to access the stub. This leaves only a couple 
of useful commands: the symbol-table commands getsyra, where, and ?, and the 
expression-type commands (where you type an expression and see the answer). 

One command which is especially useful is quit, which, when remote debugging, 
doesn't touch the slave at all, but returns the master to the desktop. If you 
want to let the client run and then leave the debugger, just type continue and 
then quit. The client will continue to run. You can even re-enter the 
debugger, and it will reestablish communications with the stub when the client 
stops. 

[Sometimes, the head and stub cannot reestablish communications, because they 
are out of synchronization. When this happens, you have to reset the client, 
hit ~C on the debugger and say quit, and start over.] 

If you issue a command which needs to use the stub, but the slave is busy run¬ 
ning the client, you will get the message "You must stop the client and use 
the wait command." This is how you resynchronize the head and the stub. Where 
continue issues a command and doesn't wait for the reply, wait waits for a 
reply without issuing a command. What it gets might be a repetition of the 
reply to the previous command, or it might be a new reply (as after a continue 
or timeout). 
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STOP BUTTONS 

The debugger supports something called a stop button. A stop button is 
any button which causes an external interrupt to occur. One of the easi¬ 
est and least-obtrusive interrupts to wire a stop button to is the "ring 
indicator” interrupt on the serial (modem) port. The instructions for 
building a stop button are at the end of this section. 

The stop button can be used any time when remote debugging, but should be 
used very carefully when debugging on one machine, especially when using 
GEMDOS or the BIOS for input from the keyboard and output to the screen. 
See the section DB AND GEMDOS in the chapter OPERATING SYSTEM CONSIDERA¬ 
TIONS for more information. 

Hitting the stop button causes an interrupt to occur. The handler for 
this interrupt checks the stub state to see if it is in a trace or go. If 
so, the trace/go is stopped, and the exception "stop button” is reported 
to the head. 

If the stub is executing, rather than the client, the fact that the stop 
button got hit is remembered. When the stub would restart the client, is 
stops instead. This will happen if, for example, the stub is processing a 
counted breakpoint whose count has not reached zero when you hit the stop 
button. 

If the stub is idle (i.e. waiting for a command) and you hit the stop but¬ 
ton, nothing happens: there is nothing to stop. 

The stop button will only work if the interrupt priority level (IPL) does 
not mask the interrupt the button causes. In the case of the ring indica¬ 
tor on the ST, this means that the IPL must be less than 6. It usually 
is, but if you have an infinite loop at IPL 6 or 7 you can't use the stop 
button to get out of it. If you had a stop button wired to the non¬ 
maskable interrupt (NMI), the IPL would not matter. 


Wiring A Ring-Indicator Stop Button 

Ring Indicator is an easy stop button to wire because the connections 
you need are outside the ST itself, and are available on almost any 
RS232 connector. The debugger, therefore, contains code to initialize 
and enable the ring-indicator interrupt. 

What you need to do is wire a button which normally connects Pin 22 
(ring indicator) to Pin 7 (ground), but when pressed connects Pin 22 
to Pin 4 (CTS, always asserted). This will detected as a change by 
the hardware, and cause the interrupt. Don't worry about debouncing 
the button: this is done in software. It turns out to be just lucky 
that the hardware does detect a change this way: zero volts (from Pin 
7) is not really a valid signal on Pin 22. 
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